feat(mix): add content-sized GridTrack.auto() rows - #1031

Related issue

None filed. Reported directly against main @ 390421be with a reproduction; investigation notes are in .context/grid-content-sized-tracks-findings.md.

Description

GridBox could not express a grid whose rows size to their tallest child, and the only available workaround silently truncated content.

Given a 2-column GridBox with four Text children of unequal height inside a SingleChildScrollView at width 400:

• no autoRows → threw Grid auto-placement requires an autoRows track
• .autoRows(.fr(1)) → threw Grid autoRows requires a bounded height for fractional tracks
• .autoRows(.fixed(40)) → no error, but the long cell was laid out at Size(194, 40) while the same text at the same width needs Size(194, 300)

The third case is the important one: performLayout gave every child a tight cell, so a child taller than its track was clipped with no diagnostic — unlike Column/Wrap, which report visible overflow. Every shipped grid example worked around this with a hardcoded row height (.fixed(116), (104), (230), (210), (220), (190)), so the gallery could only demonstrate content whose height was already known. CSS Grid's default grid-auto-rows is auto; Mix could not express the CSS default.

This adds GridTrack.auto() and makes it the default for implicit rows.

No stock Flutter widget satisfied the contract. Table has the right row-height rule but not GridBox's gaps, fixed/fr row semantics, or flat-child identity across responsive column changes; Wrap lacks shared tracks and stretch; sliver grids require delegate-chosen tile heights; CustomMultiChildLayout cannot size the parent from a measure-then-stretch pass. RenderMixGrid stays the owner and borrows RenderTable's algorithm.

Changes

Public API

• GridTrack.auto() — a fieldless, content-sized track, valid in rows and autoRows. Columns reject it with a vertical-only hint.
• An omitted autoRows now resolves to GridTrack.auto(), so a Grid with columns and no row declaration sizes each implicit row to its tallest child.
• auto interpolates with auto (constant); auto ↔ numeric track kinds snap at the animation midpoint like other incompatible kinds.

Layout (render_grid.dart)

• Fixed/fr grids keep the existing single-pass path — _hasAutoTrack short-circuits the measure pass, so those children are still laid out once.
• Auto-row children are measured at their resolved column width with a loose height; each row takes the tallest measurement; the final pass lays every child into the stretched cell so shorter siblings still fill the row.
• Live layout, dry layout, and vertical intrinsics share the geometry through Flutter's ChildLayoutHelper.layoutChild / dryLayoutChild.
• computeGridLayout now takes already-resolved rows, so implicit-row expansion happens exactly once per layout.

Protocol

• Additive v1 {"type":"auto"} nested discriminator, gated to rows, autoRows, and constraint patches. Auto tracks carry no token references. The exported schema fingerprint changes accordingly.

Docs & example

• The catalog example drops its hardcoded row heights and now renders genuinely unequal card content; both goldens regenerated.
• doc/grid-layout.md documents the row-only scope, the default for implicit rows, the bounded-height rule for fr rows, why fixed tracks clip by design, and the nesting cost.

Review Checklist

• Testing: packages/mix 2912 tests, packages/mix/example 15, packages/mix_protocol 393 — all passing. dart analyze clean on all three. New coverage includes the reported scroll-view repro, mixed auto+fixed and auto+fr rows under loose and tight bounded height, responsive remeasurement across an onConstraints breakpoint without rebuilding children, a layout-count assertion proving only auto-row children pay the second pass, live/dry/intrinsic parity, animation, seeded property tests over 200 random grids, and protocol round-trips including lenient decode of an unrecognized track.
• Breaking Changes: Yes — documented in packages/mix/CHANGELOG.md under ### Breaking changes. See below.
• Documentation Updates: doc/grid-layout.md, README.md, example/README.md, mix_protocol/GUIDE.md, mix_protocol/WIRE_CONTRACT.md, and the Grid guidance under skills/mix/.
• Website Updates: not done — btwld/mix-docs needs a matching update for the new track kind and the implicit-row default.

Additional Information

Breaking change. A GridBox that needed more rows than it declared used to throw; it now lays out with content-sized implicit rows. This applies both when no rows are declared and when an explicit rows list undershoots the child count. No currently-successful fixed/fr layout changes.

Deliberately not included: a universal overflow warning for fixed cells. A fixed track is a hard constraint in the same way a tight SizedBox is, and a reliable generic probe would need a speculative measure pass on every fixed child — which also breaks children that require a bounded height. Now that auto exists, fixed rows stay strict, and the docs say so explicitly.

Cost. Auto-row children are laid out twice (measure, then stretch). Nesting compounds this multiplicatively — a leaf inside three nested auto Grids is laid out eight times. This is inherent to the measure-then-stretch algorithm (RenderTable has it too), and is documented in both the guide and the changelog.

Scope. Content-sized columns are deliberately out. Width-dependent wrapping creates feedback between column and row sizing, and the reported use case needs content-height rows after responsive column widths are known. GridTrack.auto() should not be quietly broadened to columns later without specifying those feedback rules — the reasoning for keeping one GridTrack type rather than splitting per axis is recorded as a comment in grid_track.dart.

Wire compatibility. {"type":"auto"} is additive within v1, per WIRE_CONTRACT.md. Old strict decoders fail closed; lenient decoders warn and drop the smallest unrecognized value (now covered by a test). Payloads containing type: auto should only be produced once matching mix and mix_protocol versions ship together.